home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / DOpus_SDK_5.5 / docs / boopsi.doc < prev    next >
Text File  |  1996-09-07  |  21KB  |  472 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/BOOPSI_gadgets     
  4. dopus5.library/dopusbuttongclass  
  5. dopus5.library/dopuscheckgclass    
  6. dopus5.library/dopusframeclass    
  7. dopus5.library/dopusiclass        
  8. dopus5.library/dopuslistviewgclass
  9. dopus5.library/dopuspalettegclass 
  10. dopus5.library/dopusstrgclass     
  11. dopus5.library/dopusviewgclass    
  12. dopus5.library/BOOPSI_gadgets                   dopus5.library/BOOPSI_gadgets
  13.  
  14.     PURPOSE
  15.  
  16.     The dopus5.library makes several BOOPSI gadgets available globally. These
  17. gadgets can be accessed globally without even opening the dopus5.library,
  18. although it is a good idea to open it to make sure the library is present in
  19. the system.
  20.  
  21.     The gadgets are all sub-classes of standard BOOPSI gadgets, and so take
  22. all the standard tags (GA_Left, GA_Top, etc..). Often they are based heavily
  23. on GadTools gadgets and will support equivalent GadTools tags. They also
  24. have their own set of tags, which is described below.
  25.  
  26. dopus5.library/dopusbuttongclass             dopus5.library/dopusbuttongclass
  27.  
  28.     The dopusbuttongclass provides a standard pushbutton gadget. It is
  29. similar to a standard buttongclass gadget, but provides some additional
  30. functionality. This is via the following tags:
  31.  
  32.     GTCustom_TextAttr (struct TextAttr *) (I) - used to specify a font for
  33.         the gadget label. (default is the window font).
  34.  
  35.     GTCustom_ThinBorders (BOOL) (I) - if set to TRUE, the gadget will be
  36.         rendered with single-pixel borders (default FALSE).
  37.  
  38.     GTCustom_Borderless (BOOL) (I) - if set to TRUE, the gadget will be
  39.         rendered with no border (default FALSE).
  40.  
  41.     GTCustom_Bold (BOOL) (I) - is set to TRUE, the gadget label will be
  42.         rendered in bold (default FALSE).
  43.  
  44.     GTCustom_Style (ULONG) (I) - use this tag to control the text style of
  45.         the gadget label. Valid flags are FSF_BOLD and FSF_ITALIC
  46.         (default FSF_NORMAL).
  47.  
  48.     GTCustom_NoGhost (BOOL) (I) - if set to TRUE, the gadget imagery will
  49.         not 'ghost' when the gadget is disabled (default FALSE).
  50.  
  51.     GTCustom_TextPlacement (WORD) (I) - Lets you select the position of the
  52.         label relative to the gadget. Valid values are:
  53.  
  54.             PLACETEXT_IN (default)
  55.             PLACETEXT_LEFT
  56.             PLACETEXT_RIGHT
  57.             PLACETEXT_ABOVE
  58.  
  59. dopus5.library/dopuscheckgclass                dopus5.library/dopuscheckgclass
  60.  
  61.     The dopuscheckgclass provides a replacement for GadTools checkbox gadgets.
  62. As a BOOPSI class, it allows you to have a checkbox without using GadTools.
  63. This class uses the same basic code as the dopusbuttongclass, and as such
  64. supports the same tags. The class also supports the GTCB_Checked flag (defined
  65. in libraries/gadtools.h) to set or get the current state of the gadget.
  66.  
  67. dopus5.library/dopusframeclass                 dopus5.library/dopusframeclass
  68.  
  69.     The dopusframeclass is a BOOPSI class for a frame gadget. A frame gadget
  70. does not respond to user input; its only purpose is to draw a frame (usually
  71. around some other gadgets). This class uses the same basic code as the
  72. dopusbuttongclass, and as such supports the same tags. The class also supports
  73. the GTCustom_FrameFlags tag, to specify flags for the frame. Currently, the
  74. only defined flag is AREAFLAG_RECESSED, which causes the frame to be drawn
  75. as recessed.
  76.  
  77. dopus5.library/dopusiclass                         dopus5.library/dopusiclass
  78.  
  79.     This class allows you to access several predefined images. The image
  80. you receive is controlled by the following tags:
  81.  
  82.         DIA_Type
  83.  
  84.         This sets the image type. Current valid types are:
  85.  
  86.             IM_ARROW_UP     - an up arrow
  87.             IM_ARROW_DOWN   - a down arrow
  88.             IM_CHECK        - a check mark
  89.             IM_DRAWER       - a "folder" image
  90.             IM_BBOX         - a filled box with a border
  91.             IM_BORDER_BOX   - a filled box
  92.             IM_ICONIFY      - an iconify gadget image
  93.             IM_LOCK         - a lock gadget image
  94.  
  95.  
  96.         DIA_FrontPen
  97.  
  98.         This sets the front pen for the image. Currently, only the IM_CHECK
  99.         image supports this tag.
  100.  
  101.     This class is a sub-class of imageclass, and so supports the standard
  102. IM_Width, IM_Height, etc, tags. Images are scaled to the supplied sizes.
  103.  
  104. dopus5.library/dopuslistviewgclass         dopus5.library/dopuslistviewgclass
  105.  
  106.     This boopsi gadget is a replacement for the gadtools LISTVIEW_KIND
  107.     gadgets. It has been designed to "drop-in" as easily as possible, and
  108.     uses many of the same tags as the gadtools equivalent. It is however
  109.     much more flexibile than the gadtools gadget.
  110.  
  111.     The gadget duplicates most of the tags provided by gadtools' listview
  112.     gadget. It also offers some powerful additions not available under
  113.     gadtools. These include :
  114.  
  115.         o Current selection indicated by highlight bar, checkmark
  116.           or text colour
  117.         o Multiple-selection of items with checkmarks
  118.         o Items can be rendered in different colours
  119.         o Simple text formatting in the lister
  120.         o Scroller can be optionally removed
  121.         o Supports drag notification
  122.         o Automatic double-click notification
  123.         o Supports resizing via OM_SET
  124.  
  125.     It also does not suffer from the gadtools problem of resizing itself to an
  126.     integral multiple of the item height (ie, the size you specify is the size
  127.     you get). It is controlled by the following tags:
  128.  
  129.     DLV_Top (WORD) (ISG) - Top item visible in the listview.  This value
  130.         will be made reasonable if out-of-range (defaults to 0).
  131.  
  132.     DLV_MakeVisible (WORD) (IS) - Number of an item that should be forced
  133.         within the visible area of the listview by doing minimal scrolling.
  134.         This tag overrides DLV_Top.
  135.  
  136.     DLV_Labels (struct List * or Att_List *) (ISG) - List of nodes whose
  137.         ln_Name fields are to be displayed in the listview. Calling
  138.         SetGadgetAttrs() and specifying 0 will remove the current list.
  139.         Specifying ~0 will remove the list but will not disturb the display,
  140.         allowing you to make changes to the contents and selection status.
  141.  
  142.     DLV_ReadOnly (BOOL) (I) - If TRUE, then listview is read-only
  143.         (defaults to FALSE).
  144.  
  145.     DLV_ScrollWidth (UWORD) (I) - Width of scroll bar for listview.
  146.         Must be greater than zero (defaults to 16).
  147.  
  148.     DLV_ShowSelected (void) (I) - Specify this tag to have the currently
  149.         selected item displayed with a highlight bar (or another method).
  150.         Note that this tag does not support the automatic copying to
  151.         a string gadget that gadtools does. You should specify ti_Data
  152.         as 0 for future compatibility.
  153.  
  154.     DLV_Selected (UWORD) (ISG) - Ordinal number of currently selected
  155.         item, or ~0 to have no current selection (defaults to ~0).
  156.  
  157.     DLV_TextAttr (struct TextAttr *) (I) - Allows you to specify a font to
  158.         use in the lister. Must have previously been opened.
  159.  
  160.     DLV_MultiSelect (BOOL) (I) - If TRUE, the listview allows multiple-
  161.         selection of items (see below for details).
  162.  
  163.     DLV_Check (BOOL) (I) - If TRUE, and DLV_ShowSelected is TRUE, the
  164.         current selection will be indicated with a checkmark. Note that
  165.         this tag has no meaning in conjunction with DLV_MultiSelect.
  166.  
  167.     DLV_ShowChecks (ULONG) (I) - If set to something other than zero,
  168.         checkmarks will be shown for selected items (see below for
  169.         details), but the user will not be able to alter their state.
  170.  
  171.         If set to 1, selected items will be rendered in the highlight
  172.         pen colour. If set to 2, they will be rendered in the normal
  173.         text colour.
  174.  
  175.     DLV_Highlight (BOOL) (I) - If TRUE, and DLV_ShowSelected is TRUE, the
  176.         current selection will be displayed in a different colour.
  177.  
  178.     DLV_NoScroller (BOOL) (I) - If TRUE, the lister will not have a scroller
  179.         attached. The gadget will still support scrolling by "dragging"
  180.         the selection highlight.
  181.  
  182.     DLV_TopJustify (BOOL) (I) - If TRUE, items displayed in the lister will
  183.         be aligned to the top of the gadget, rather than being centered
  184.         vertically.
  185.  
  186.     DLV_Flags (ULONG) (I) - Allows you to specify layout flags for the lister.
  187.         Currently the only flags supported are :
  188.  
  189.                 PLACETEXT_ABOVE - display title above gadget (default)
  190.                 PLACETEXT_LEFT  - display title at top-left of gadget
  191.  
  192.     DLV_RightJustify (BOOL) (I) - If TRUE, items displayed in the lister
  193.         will be aligned to the right of the gadget, rather than to the
  194.         left.
  195.  
  196.     DLV_ShowFilenames (BOOL) (I) - If TRUE, items in the lister are taken to
  197.         be pathnames to files, and only the filename component (ie the
  198.         result of a FilePart() call) is displayed. This allows you to keep
  199.         the full pathname in ln_Name but only display the filename.
  200.  
  201.     DLV_DragNotify (ULONG) (I) - If this is set to something other than zero,
  202.         the gadget will notify you when the user tries to drag an item
  203.         out of it. See the section on DragNotify below.
  204.  
  205.     DLV_ScrollUp (void) (S) - Use this tag with SetGadgetAttrs() to make the
  206.         lister scroll up one line.
  207.  
  208.     DLV_ScrollDown (void) (S) - Use this tag with SetGadgetAttrs() to make the
  209.         lister scroll down one line.
  210.  
  211.     DLV_SelectPrevious (void) (S) - Use this tag with SetGadgetAttrs() to make
  212.         the previous entry become selected.
  213.  
  214.     DLV_SelectNext (void) (S) - Use this tag with SetGadgetAttrs() to make
  215.         the next entry become selected.
  216.  
  217.     DLV_Lines (void) (G) - returns number of visible lines displayed in lister.
  218.  
  219.     DLV_Object (void) (G) - returns the address of the Object * structure.
  220.  
  221.     DLV_GetLine (void) (G) - this allows you to get the line number in the
  222.         lister from window-relative mouse coordinates. StoragePtr should be
  223.         initialised to the mouse coordinates ((x<<16)|y).
  224.  
  225.     DLV_DrawLine (void) (G) - this allows you to render a line of the listview
  226.         into your own RastPort. See the section on DragNotify below
  227.         for more information.
  228.  
  229.     The gadget is a subclass of gadgetclass and as such supports the
  230.     standard gadgetclass tags (including GA_Disabled). The title of
  231.     the gadget can be specified with GA_Text (GA_IntuiText and
  232.     GA_LabelImage are not supported).
  233.  
  234.  
  235.    MULTIPLE SELECTION
  236.  
  237.     The dopuslistviewgclass gadget supports multiple-selection of items.
  238.     This feature is enabled by passing {DLV_MultiSelect,TRUE} on creation.
  239.     The ln_Type field of each of the node structures is used to
  240.     indicate whether an item is selected or not. For convenience, this
  241.     field has been renamed lve_Flags.
  242.  
  243.     To see whether an item is selected, test the LVEF_SELECTED flag in
  244.     the lve_Flags field. Similarly, you can set an item's selection
  245.     status by changing the value of this flag.
  246.  
  247.  
  248.    CUSTOM PEN COLOURS
  249.  
  250.     You can specify the individual pen colours of each of the items in
  251.     the list. The ln_Pri field of each of the node structures is used
  252.     for this purpose. For convenience, this field has been renamed
  253.     lve_Pen.
  254.  
  255.     To specify that an item is to be rendered in other than the default
  256.     pen colour, set lve_Pen to the appropriate value and set the
  257.     LVEF_USE_PEN flag in the lve_Flags field.
  258.  
  259.  
  260.    TEXT FORMATTING
  261.  
  262.     The gadget supports simple text-formatting for item display. This
  263.     allows you to have columns and right-justified text in the lister.
  264.  
  265.     If the text for an entry (ln_Name) contains a \t (tab character),
  266.     the text following that character will be right-justified in the
  267.     lister.
  268.  
  269.     You can specify column positions using the \a (alert) character.
  270.     The character immediately following the \a provides the position
  271.     for the start of the next column. This is specified in character
  272.     spaces. You should be aware that characters in proportional fonts
  273.     are often wider than the nominal width of the font.
  274.  
  275.     For example, if the following items were supplied to the gadget :
  276.  
  277.         Bloggs\a\xa Fred\a\x1a 1-Sep-65\tPaid
  278.         Hall\a\xa Jane\a\x1a 9-Aug-68\tNot paid
  279.         Hubbard\a\xa Bill\a\x1a 7-Mar-18\tPaid
  280.  
  281.     The display you would see would be something like this :
  282.  
  283.         Bloggs    Fred            1-Sep-65          Paid
  284.         Hall      Jane            9-Aug-68      Not paid
  285.         Hubbard   Bill            7-Mar-18          Paid
  286.  
  287.  
  288.    DRAG NOTIFICATION
  289.  
  290.     To enable drag notification, pass {DLV_DragNotify,1} on creation.
  291.     You will then be sent an extended taglist via the IDCMP_IDCMPUPDATE
  292.     message when the user attempts to drag an item out of the list.
  293.     If you pass {DLV_DragNotify,2} the user will only be able to drag
  294.     out of the list sideways; dragging up or down will scroll the list
  295.     as usual.
  296.  
  297.     The tags you are sent on an attempted drag are as follows :
  298.  
  299.         Tag         Data
  300.  
  301.         GA_ID               gadget ID
  302.         GA_Left
  303.         GA_Top              window-relative item coordinates
  304.         GA_Width
  305.         GA_Height           size of the item as displayed
  306.         GA_RelRight
  307.         GA_RelBottom        offset mouse position in item
  308.         DLV_Top             top item number
  309.         DLV_DragNotify      ordinal number of item dragged
  310.  
  311.     To see if an IDCMP_IDCMPUDPATE message is from a drag, just test
  312.     for the presence of the DLV_DragNotify tag in the taglist.
  313.  
  314.     Once you get a drag notification, the actual dragging of the item
  315.     is your responsibility. The easiest way is using the drag routines
  316.     provided by the dopus5.library. Create a DragInfo large enough for the
  317.     item (GA_Width and GA_Height in the taglist). There are two ways to get
  318.     the image for the bitmap.
  319.  
  320.     The first way is to use the GA_Left and GA_Top coordinates in the
  321.     taglist and just ClipBlit() from your window into the drag rastport.
  322.     This is the easiest way, but will also copy the checkmark if there is
  323.     one, and you may not want that.
  324.  
  325.     The second way is to use the DLV_DrawLine tag with the GetAttr()
  326.     call, and have the listview render the item into your bitmap for you.
  327.  
  328.     To do this, you need to initialise a ListViewDraw structure :
  329.  
  330.         lvdraw.rp           RastPort to render into
  331.         lvdraw.drawinfo     DrawInfo for the screen
  332.         lvdraw.node         List node to render
  333.         lvdraw.line         Set to 0
  334.         lvdraw.box.Left     Set to 0
  335.         lvdraw.box.Top      Set to 0
  336.         lvdraw.box.Width    Width of BitMap
  337.         lvdraw.box.Height   Height of BitMap
  338.  
  339.     Then you pass the address of the ListViewDraw structure as the
  340.     StoragePtr for the GetAttr call. Eg,
  341.  
  342.         ULONG *ptr=(ULONG)&lvdraw;
  343.         Object *obj=GetTagData(DLV_Object,0,tags);
  344.  
  345.         GetAttr(DLV_DrawLine,obj,&ptr);
  346.  
  347.     The GA_RelRight and GA_RelBottom tags are used to indicate where
  348.     in the item the user clicked. When you display the drag image on
  349.     the screen, you should offset its position by these values.
  350.  
  351.  
  352.    DOUBLE-CLICK NOTIFICATION
  353.  
  354.     If you get an IDCMP_IDCMPUPDATE message from the gadget, and the
  355.     DLV_DragNotify tag is not set, it is a normal selection message.
  356.     An additional tag is sent in this situation; DLV_DoubleClick.
  357.     The ti_Data field is a boolean indicating whether the selection
  358.     is a double-click or a normal single click.
  359.  
  360.     The tags now sent for this message are :
  361.  
  362.         Tag                 Data
  363.  
  364.         GA_ID               Gadget ID
  365.         DLV_Selected        Ordinal number of selection
  366.         DLV_DoubleClick     BOOL
  367.  
  368.  
  369.    RESIZING
  370.  
  371.     To resize the gadget, pass the new coordinates via GA_Left, GA_Top,
  372.     GA_Width and GA_Height in a SetGadgetAttrs() call. You will then need
  373.     to refresh the display yourself, usually by clearing the window and
  374.     calling RefreshGList(). You may also need to call RefreshWindowFrame(),
  375.     if the window has been resized smaller, as the gadget may have
  376.     overwritten the window border before it was resized.
  377.  
  378. dopus5.library/dopuspalettegclass           dopus5.library/dopuspalettegclass
  379.  
  380.     The dopuspalettegclass provides a replacement for GadTools PALETTE_KIND
  381. gadgets. As a BOOPSI class, it allows you to have a palette gadget without
  382. using GadTools. This class supports the following tags:
  383.  
  384.     GTCustom_TextAttr (struct TextAttr *) (I) - used to specify a font for
  385.         the gadget label. (default is the window font).
  386.  
  387.     GTCustom_ThinBorders (BOOL) (I) - if set to TRUE, the gadget will be
  388.         rendered with single-pixel borders (default FALSE).
  389.  
  390.     GTPA_Color (UBYTE) (ISG) - the currently selected colour of the palette.
  391.         This number is a pen number, and not the ordinal colour number within
  392.         the palette gadget itself (default 1).
  393.  
  394.     GTPA_Depth (UWORD) (IS) - Number of bitplanes in the palette (default 1).
  395.  
  396.     GTPA_ColorTable (UBYTE *) (IS) - Pointer to a table of pen numbers
  397.         indicating which colours should be used and edited by the palette
  398.         gadget. This array must contain as many entries as there are colours
  399.         displayed in the palette gadget. The array provided with this tag
  400.         must remain valid for the life of the gadget, or until a new table
  401.         is provided. (default is NULL, which causes a 1-to-1 mapping of pen
  402.         numbers).
  403.  
  404.     GTPA_NumColors (UWORD) (IS) - Number of colours to display in the palette
  405.         gadget. This overrides GTPA_Depth and allows numbers which aren't
  406.         powers of 2. (defaults to 2)
  407.  
  408.     DPG_Pen (UWORD) (ISG) - the currently selected colour of the palette.
  409.         This is similar to GTPA_Color but referes to the ordinal colour
  410.         number and not the pen number itself.
  411.  
  412.     DPG_SelectNext (void) (S) - use this tag with SetGadgetAttrs() to cause
  413.         the next colour in the gadget to be selected.
  414.  
  415.     DPG_SelectPrevious (void) (S) - use this tag with SetGadgetAttrs() to
  416.         cause the previous colour in the gadget to be selected.
  417.  
  418. dopus5.library/dopusstrgclass                   dopus5.library/dopusstrgclass
  419.  
  420.     This dopusstrgclass provides a replacement for GadTools STRING_KIND
  421. gadgets. It is basically a standard string gadget with an automatic border,
  422. but also supports additional features. This class is based on the
  423. dopusbuttongclass, and as such supports all the tags of that class. It is
  424. also a subclass of strgclass and supports the standard string gadget
  425. tags of that class (with some important changes, listed below). The control
  426. tags supported by this class are as follows:
  427.  
  428.     STRINGA_Buffer (char *) (I) - Specify the main buffer for the gadget.
  429.         If this is not supplied, a buffer will be allocated automatically
  430.         (this does not suffer from the maximum 128 bytes limitation of the
  431.         standard BOOPSI string gadget class).
  432.  
  433.     STRINGA_UndoBuffer (char *) (I) - Specify the undo buffer for the
  434.         gadget. Again, one will be allocated automatically if you do not
  435.         supply one.
  436.  
  437.     STRINGA_WorkBuffer (char *) (I) - Specify the work buffer for the
  438.         gadget. This will also be automatically allocated if you do not
  439.         supply it.
  440.  
  441.     STRINGA_MaxChars (long) (I) - Specify the maximum length of the string
  442.         editable by this gadget. If buffers are allocated automatically,
  443.         they will be this size. GTST_MaxChars and GTIN_MaxChars are also
  444.         synonyms for this tag. (defaults to 40).
  445.  
  446.     STRINGA_Font (struct TextFont *) (I) - Specify the font to use for this
  447.         gadget.
  448.  
  449.     GTCustom_ChangeSigTask (struct Task *) (I) - Specify a task that is to
  450.         be signalled whenever the contents of this gadget change.
  451.         (defaults to NULL).
  452.  
  453.     GTCustom_ChangeSigBit (BYTE) (I) - Specify the signal bit that is used
  454.         to signal a task whenever the contents of this gadget change.
  455.         (defaults to 0).
  456.  
  457.     STRINGA_TextVal (char *) (IS) - Set the contents of the string gadget.
  458.         The supplied string is copied to the buffer. GTST_String, GTTX_Text,
  459.         GTIN_Number and GTNM_Number are valid synonyms for this tag.
  460.  
  461.     To use the dopus5.library edit hook with a string gadget, you should call
  462. GetEditHook() and pass the results with the STRINGA_EditHook tag.
  463.  
  464. dopus5.library/dopusviewgclass                 dopus5.library/dopusviewgclass
  465.  
  466.     This class provides a simple view gadget, similar to GadTools TEXT_KIND
  467. and NUMBER_KIND gadgets. It is a subclass of dopusbuttongclass, and so
  468. supports all the tags of that class. To set the contents of the view gadget,
  469. use the GTTX_Text or GTNM_Number tags (a view gadget can be used to display
  470. either text or a number interchangeably).
  471.  
  472.